This document describes the ZoneRanger application, and is divided into the following sections:
Beta Version
Background Information
About ZoneRanger
Overview Window
Zone Window
Apple Menu
File Menu
Edit Menu
Zones Menu
Configure Menu
Special Menu
Help Menu
Overview Window Popup Menu
Zone Window Popup Menu
Find Dialog
Shortcuts
System Requirements
Known Limitations
Known Bugs
Features in Version 0.9.5
Bug Fixes in Version 0.9.5
Copyright Notice
Source Code
Special Thanks
Comments and Suggestions
The reader is encouraged to read the entire document; if, however, one wants to get off to a quick start, one should read from the "System Requirements" section to the end of the document.
B E T A V E R S I O N
This is a beta version of the ZoneRanger application. If you find any bugs with the program, or have any comments or suggestions you would like to make, please send them to the address listed at the end of this document.
B A C K G R O U N D I N F O R M A T I O N
Each process on the Macintosh is associated with a heap zone, out of which the Memory Manager allocates memory blocks on behalf of the process. A heap zone contains a zone header followed by a series of memory blocks, each of which contains a block header followed by the contents of the block. A block header contains the size, type, and attributes of the block.
A block type is either relocatable, non-relocatable, or free. A relocatable block is one that the Memory Manager can move around the heap zone as needed, and contains the data that is referenced by a handle. A non-relocatable block is one that cannot move around the heap zone, and contains the data that is referenced by a pointer. A free block is unallocated, and the contents of the block are undefined. For the sake of simplicity, we shall refer to relocatable blocks as handles and non-relocatable blocks as pointers.
There are three block attributes, and they apply only to relocatable blocks: locked, purgeable, and resource. If a relocatable block has the locked attribute set, then it cannot be moved around the heap zone. If a relocatable block has the purgeable attribute set, then it can be converted to a free block if necessary. If a relocatable block has the resource attribute set, then it contains the data from a resource. For the sake of simplicity, we shall refer to these types of blocks as locked handles, purgeable handles, and resource handles, respectively.
The reader is referred to the "Memory" volume of "Inside Macintosh" for more detailed information about the structure of heap zones and memory blocks.
A B O U T Z O N E R A N G E R
ZoneRanger provides detailed information about each heap zone that is currently active on the Macintosh. This information includes both the counts and total sizes of the free blocks, pointers, handles, locked handles, purgeable handles, and resource handles in each heap zone.
ZoneRanger also provides windows in which a heap zone can be displayed graphically, with the size, type, and attributes of each block clearly defined. The user can control the resolution and zoom factor of this display, as well as click on any individual block to view its contents.
O V E R V I E W W I N D O W
There are two types of windows in ZoneRanger, a single Overview window and a set of Zone windows. Balloon help is available for all windows.
The Overview window is divided into seven columns, and has one row for each currently active heap zone. The first column is titled "Name" and contains the name of the process associated with the heap zone. The next three columns are titled "Free Blocks", "Pointers", and "Handles…", and contain the numbers of free blocks, pointers, and handles in the heap zone. The final three columns are titled with icons representing locked, purgeable, and resource handles, and contain the numbers of locked, purgeable, and resource handles, respectively.
Although the Overview window defaults to displaying the numbers of the different types of blocks, the user can configure whether the Overview window displays the numbers, total sizes, or percentage of these different block types in the heap zone. The user can also configure whether these figures are displayed in decimal or hexadecimal notation.
The user can click on any heap zone in the Overview window in order to pop up a list of operations that can be performed on that heap zone. If Balloon Help is enabled when the user clicks on a heap zone, then help balloons will appear which explain the operations in more detail. One should read the "Overview Window Popup Menu" section for a complete description of these operations.
Z O N E W I N D O W
The user can open one Zone window for each heap zone that is listed in the Overview window. The zone window displays a graphic representation of the heap zone in two dimensions. Each type of block in distinguished by the pattern in which it is drawn: free blocks are drawn in white, pointers are drawn in black, and handles are drawn in gray.
Although memory is inherently one-dimensional, the second dimension of the display is achieved by wrapping the display to the width of the window. Specifically, the zone window is a two-dimensional grid in which each square represents a fixed number of bytes in the heap zone. This number of bytes is referred to as the "resolution" of the zone window, and can be configured by the user. If a given block is larger than the current resolution, then it will appear in the display as spanning the appropriate number of grid squares. If the given block is smaller than the current resolution, then it would occupy less than a single grid square, and may not appear in the display at all. Since even the smallest block must contain the block header which is either 8 or 12 bytes, one should set the resolution to 8 bytes in order to ensure that all blocks are displayed. The default resolution for a zone window is 32 bytes.
In addition, the user can configure the pixel size of each grid square, which is referred to as the "zoom factor" of the zone window. The allowable zoom factors are 1x1, 4x4, and 8x8 pixel squares. The default zoom factor for a zone window is 4x4.
The user can also configure whether the boundaries of each individual block are shown. In "Block View", all of the grid squares that comprise a given block are displayed as a contiguous set, and the boundaries of the block are clearly marked. In "Grid View", each grid square is drawn using the pattern representing the type of block in which it is contained, but there is no indication of where one block ends and the next one begins. The grid view of a heap zone presents less information than the block view, but can be drawn faster because it does not have to calculate and draw the block boundaries.
Finally, the user can click on any block in the heap zone to pop up information about the block and a display of its contents, both of which can be either copied to the clipboard or saved to a TEXT file. If Balloon Help is enabled when the user clicks on the block, then help balloons will appear which explain information about the contents of the block in more detail. One should read the "Zone Window Popup Menu" section for a complete description of this functionality.
A P P L E M E N U
ZoneRanger contains five menus: "File", "Edit", "Zones", "Configure", and "Special". It also adds menu items to the standard Apple and Help menus. Balloon help is available for all menus.
The Apple menu contains two menu items belonging to ZoneRanger, "About ZoneRanger…" and "Legend…".
The "About ZoneRanger…" menu item opens the about box for ZoneRanger.
The "Legend…" menu item opens a dialog which contains a description of which patterns are used to display each of the different block types in a zone window. This menu item is active when a Zone window is frontmost.
F I L E M E N U
The File menu contains two menu items, "Close" and "Quit".
The "Close" menu item closes the frontmost window. This menu item is active when there is a window open.
The "Quit" menu item quits the ZoneRanger application.
E D I T M E N U
The Edit menu contains the menu items for performing the required editing operations, "Undo", "Cut", "Copy", "Paste", and "Clear". None of these menu items is used by ZoneRanger.
The Edit menu contains two additional menu items, "Find…" and "Cancel Find".
The "Find…" menu item opens the Find Dialog, which is used to find blocks that are of a certain type, certain size, or contain a certain pattern. One should read the "Find Dialog" section for a complete description of this dialog. This menu item is active when a Zone window is frontmost.
The "Cancel Find" menu item cancels the current find operation. This menu item is active when a Zone window is frontmost, and a find operation has been made.
Z O N E S M E N U
The Zones menu contains the "Overview" menu item, and one menu item for each of the heap zones that is listed in the Overview window.
The "Overview" menu item will open the Overview window, or bring the window to the front if it is already open.
The remaining menu items will each open a zone window displaying the heap zone for the process for which the menu item is named, or bring the window to the front if it is already open.
C O N F I G U R E M E N U
The Configure menu contains menu items that the user can use to configure the display of the frontmost window.
The "Display Block Sizes" menu item sets the Overview window to display the total sizes of the various types of blocks in each heap zone. Selecting this menu item will place a checkmark next to the item, and will deselect "Display Block Counts" and "Display Block Usage". This menu item is active when the Overview window is frontmost.
The "Display Block Counts" menu item sets the Overview window to display the total counts of the various types of blocks in each heap zone. Selecting this menu item will place a checkmark next to the item, and will deselect "Display Block Sizes" and "Display Block Usage". This menu item is active when the Overview window is frontmost.
The "Display Block Usage" menu item sets the Overview window to display the usage thermometer of the various types of blocks in each heap zone. A usage thermometer shows the percentage of the entire heap zone occupied by blocks of the given type. Selecting this menu item will place a checkmark next to the item, and will deselect "Display Block Sizes" and "Display Block Counts". This menu item is active when the Overview window is frontmost.
The "Display Decimal" menu item sets the Overview window to display the sizes or counts of the various types of blocks in each heap zone in decimal notation. Selecting this menu item will place a checkmark next to the item, and will deselect "Display Hexadecimal". This menu item is active when the Overview window is frontmost.
The "Display Hexadecimal" menu item sets the Overview window to display the sizes or counts of the various types of blocks in each heap zone in hexadecimal notation. Selecting this menu item will place a checkmark next to the item, and will deselect "Display Decimal". This menu item is active when the Overview window is frontmost.
The "Block View" menu item sets the zone window to display the boundaries of each block in the zone. Selecting this menu item will place a checkmark next to the item, and will deselect "Grid View". This menu item is active when a zone window is frontmost.
The "Grid View" menu item sets the zone window to suppress the display of the boundaries of each block in the zone. Selecting this menu item will place a checkmark next to the item, and will deselect "Block View". This menu item is active when a zone window is frontmost.
The "Show Locked Handles" menu item will display all locked handles in a dark gray pattern. This menu item is active when a zone window is frontmost. Selecting this menu item will place a checkmark next to the item, and will deselect "Show Purgeable Handles" and "Show Resource Handles". This menu item is active when a zone window is frontmost.
The "Show Purgeable Handles" menu item will display all purgeable handles in a light gray pattern. Selecting this menu item will place a checkmark next to the item, and will deselect "Show Locked Handles" and "Show Resource Handles". This menu item is active when a zone window is frontmost.
The "Show Resource Handles" menu item will display all resource handles in a diamond pattern. Selecting this menu item will place a checkmark next to the item, and will deselect "Show Locked Handles" and "Show Purgeable Handles". This menu item is active when a zone window is frontmost.
The "Increase Resolution" menu item increases the resolution of the display by a factor of two. It accomplishes this by halving the number of bytes represented by each grid square. The maximum allowable resolution is 8 bytes per grid square. This menu item is active when a zone window is frontmost, and the resolution is not already at the maximum.
The "Decrease Resolution" menu item decreases the resolution of the display by a factor of two. It accomplishes this by doubling the number of bytes represented by each grid square. The minimum allowable resolution is 1,048,576 bytes (one megabyte) per grid square. This menu item is active when a zone window is frontmost, and the resolution is not already at the minimum.
The "Zoom In" menu item increases the size of each grid square in the display. The allowable zoom factors are 1x1, 4x4, and 8x8 pixel grid squares. Furthermore, the 1x1 pixel zoom factor is not available when the display is in "Block View", since a one pixel square is not sufficiently large to draw the outline of the block. This menu item is active when a zone window is frontmost, and the zoom factor is not already at the maximum.
The "Zoom Out" menu item decreases the size of each grid square in the display. The allowable zoom factors are 1x1, 4x4, and 8x8 pixel grid squares. Furthermore, the 1x1 pixel zoom factor is not available when the display is in "Block View", since a one pixel square is not sufficiently large to draw the outline of the block. This menu item is active when a zone window is frontmost, and the zoom factor is not already at the minimum.
The "Refresh Foreground" menu item presents a "slider" submenu from which the user can specify how often the application will refresh the windows when the application is in the foreground. The user can choose a value in the range from 1 to 5 seconds, as well as "always" or "never".
The "Refresh Background" menu item presents a "slider" submenu from which the user can specify how often the application will refresh the windows when the application is in the background. The user can choose a value in the range from 1 to 5 seconds, as well as "always" or "never".
S P E C I A L M E N U
The Special menu contains menu items that perform a variety of specialized operations.
The "Debugger…" menu item drops the user down into the installed debugger. To return to ZoneRanger from the debugger, the user should issue the appropriate "go" command for the debugger. From MacsBug, the user should type "g" followed by a carriage return. From The Debugger from Jasik Designs, the user should select "Exit To Program" from the "Go" menu. This menu item is active when a debugger is installed, and has been tested with MacsBug and The Debugger. It should also be active when TMON is installed.
The "Compact" menu item compacts the heap zone. The compaction process involves moving unlocked handles toward the bottom of the heap, and merging together free blocks. This menu item is active when a zone window is frontmost.
The "Purge" menu item purges the heap zone. The purging process involves changing unlocked, purgeable handles to free blocks. This menu item is active when a zone window is frontmost.
The "Compact and Purge" menu item compacts and purges the heap zone. The purging process involves changing unlocked, purgeable handles to free blocks; the compaction process involves moving unlocked handles toward the bottom of the heap, and merging together free blocks. This menu item is active when a zone window is frontmost.
The "Bring To Front" menu item bring the process associated with the heap zone to the front; that is, makes it the current application. This menu item is active when a zone window is frontmost, the process for the heap zone is not background-only, and the process is not already frontmost.
H E L P M E N U
The Help menu contains standard menu items that are used for Balloon Help, and is available on Macintoshes that are running System 7 or later.
The "About Balloon Help…" menu item opens a dialog which contains information about Balloon Help.
The "Show Balloons" menu item turns on Balloon Help. When Balloon Help is on, ZoneRanger provides help balloons for all menus, popup menus, and windows. When the menu item is selected, its name changes to "Hide Balloons". Selecting the menu item again will turn off Balloon Help.
O V E R V I E W W I N D O W P O P U P M E N U
The popup menu for the Overview window contains menu items that perform operations on the heap zone that is currently selected in the window.
The "Open Zone…" menu item opens a Zone window for the selected heap zone. This is equivalent to choosing the menu item for the appropriate heap zone from the Zones menu.
The "Compact", "Purge", "Compact and Purge", and "Bring To Front" menu items perform the same operations on the selected heap zone as the same menu items on the Special menu perform on the frontmost Zone window. One should read the "Special Menu" section for a complete description of these items.
Z O N E W I N D O W P O P U P M E N U
The popup menu for the Zone window contains information about and the contents of the block that is currently selected in the window.
The information about the block includes its type, size, address, and attributes. If the block is a resource handle, then the information also includes the type, number, and name of the resource. One should read the help balloons for this popup menu for a more complete description of this information.
The contents of the block are displayed in 8 byte increments, with a hexadecimal display of the bytes on the left and an ASCII display on the right. If the size of the block is greater than 256 bytes, then only the first 256 bytes of the contents will be displayed.
The "Options…" menu item at the bottom of the menu presents a submenu that contains the "Copy To Clipboard" and "Save To File…" menu items.
The "Copy To Clipboard" menu item will copy the contents of the popup menu, i.e. the information about and the contents of the selected block, to the Clipboard.
The "Save To File…" menu item will allow the user to save the contents of the popup menu, i.e. the information about and the contents of the selected block, to a TEXT file.
F I N D D I A L O G
The Find dialog allows the user to find those blocks in a Zone window that are of a certain type, certain size, or contain a certain pattern. Once the user has specified one or more of these criteria, then any blocks that qualify (satisfy all of the specified criteria) will be hilited in a diagonal pattern.
The dialog is divided into three sections, one for each of the criteria: "Block Type", "Block Size", and "Block Contents".
The "Block Type" section allows the user to specify the type of block. The section contains three radio buttons and three checkboxes.
The "All" radio button specifies that all blocks qualify.
The "Pointer" radio button specifies that only pointers qualify.
The "Handle" radio button specifies that only handles qualify.
The "Locked" checkbox specifies the locked status that a handle must have to qualify: checked -> locked, unchecked -> unlocked.
The "Purgeable" checkbox specifies the purgeable status that a handle must have to qualify: checked -> purgeable, unchecked -> non-purgeable.
The "Resource" checkbox specifies the resource status that a handle must have to qualify: checked -> resource, unchecked -> non-resource.
The "Block Size" section allows the user to specify the size of the block. The section contains two entry boxes.
The first entry box specifies the minimum size that a block must have to qualify.
The second box specifies the maximum size that a block must have to qualify.
If both boxes are empty, then all block sizes qualify.
The "Block Contents" section allows the user to specify a pattern that the block must contain. The section contains one entry box, two radio buttons, and one checkbox.
The entry box specifies the pattern that a block must contain to qualify.
The "ASCII" radio button specifies that the pattern is an ASCII string, and must contain an arbitrary number of ASCII characters.
The "Hexadecimal" radio button specifies that the pattern is a hexadecimal string, and must contain an even number of the characters 0-9, A-F.
The "Case Sensitive" checkbox specifies whether the search for an ASCII string should be sensitive to the case of the string.
Command-key equivalents are available for all dialog items. One should read the help balloons for this dialog for a more complete description of these dialog items.
S H O R T C U T S
There are a handful of shortcuts that are available for ZoneRanger.
If Balloon Help is available, then holding down the option key when clicking the mouse in a menu will turn on the help balloons until the mouse button is released. Similarly, holding down the option key when opening a popup menu will turn on the help balloons until the mouse button is released. This is a useful way to quickly receive help for a menu item or items without explicitly turning Balloon Help on and off manually.
Holding down the command key will turn on the "Display Block Sizes" menu item as long as the key remains depressed. This shortcut works whether ZoneRanger is in the foreground or the background. This is a useful way to toggle between display modes temporarily, without having to bring ZoneRanger to the foreground or go to the Configure menu.
Holding down the option key will turn on the "Display Block Counts" menu item as long as the key remains depressed. This shortcut works whether ZoneRanger is in the foreground or the background. This is a useful way to toggle between display modes temporarily, without having to bring ZoneRanger to the foreground or go to the Configure menu.
Holding down the control key will turn on the "Display Block Usage" menu item as long as the key remains depressed. This shortcut works whether ZoneRanger is in the foreground or the background. This is a useful way to toggle between display modes temporarily, without having to bring ZoneRanger to the foreground or go to the Configure menu.
When the Find Dialog is open, holding down the option key will display the command key equivalents for all of the dialog items, as long as the key remains depressed. If Balloon Help is available, then the help balloons will be turned on while the option key is pressed.
S Y S T E M R E Q U I R E M E N T S
ZoneRanger requires System 7 or later.
K N O W N L I M I T A T I O N S
ZoneRanger makes every attempt to operate smoothly under low-memory conditions; the Macintosh Toolbox, however, does not. As such, if the application runs out of memory during a toolbox call, ZoneRanger will return to the Finder without any warning to the user. Since the application is already out of memory, the trick is to determine how to inform the user of what has happened without allocating any memory.
ZoneRanger does not provide a colorized interface.
K N O W N B U G S
When a zone window for ZoneRanger itself is open, it is possible to pop up a display of the single free block out of which the toolbox will allocate the memory it needs to pop up the block. Between the time that the user clicks on this special free block and the block is popped up, a portion of the block has been allocated and is no longer free. As such, random data will appear in the popup. This bug only occurs in a zone window for ZoneRanger itself, and only for a single free block within this window.
F E A T U R E S I N V E R S I O N 0 . 9 . 5
Added support for 24-bit addressing.
Added a preferences file. ZoneRanger will now save the size, location, and configuration of all windows.
Added ability to find blocks in a heap zone according to their type, size, or contents.
Added ability to control the rates at which the windows are refreshed when ZoneRanger is in the foreground and when it is in the background.
Added popup menu to Overview window.
Added more detailed balloon help.
Added more status information to Zone window.
Enhanced memory management.
Enhanced stack usage.
Enhanced segmentation strategy.
Enhanced drawing speed in Zone window.
Enhanced error handling.
B U G F I X E S I N V E R S I O N 0 . 9 . 5
ZoneRanger uses a single offscreen drawing world for all open windows, which is sized to accommodate the largest of the windows. When the largest window was closed, the offscreen world was not reduced appropriately.
If an application name contained characters that are meaningful to the menu manager ( "(", "-", "/" ), then strange things would appear in the Zones menu for that application.
It would sometimes be difficult to bring a window to the front by clicking on the title bar of the window.
The scroll bar in the Zone window for a particularly large zone would sometimes behave erratically.
The maximum size to which a Zone window could be grown was the size of the main monitor. This proved to be a bad assumption if the main monitor were the smallest monitor on the system.
The Zone window did not refresh properly when it detected that its heap zone had increased in size.
A bug exists in the Window Manager of the Macintosh Toolbox in which the grow box for a window, which includes the outline of the scroll bars, is drawn one pixel too low if the window is resized while the left edge of the window is off the screen. To minimize this unsightly problem, ZoneRanger will redraw the outline of the horizontal scroll bar in its proper position.
ZoneRanger is free; it may be freely copied and distributed, provided that this copyright notice is preserved on all copies. The software may not, however, be sold or distributed for profit, or included with other software which is sold or distributed for profit, without the permission of the author.
S O U R C E C O D E
The source code for the program can be purchased for $20, and is available from the author at the address below.
S P E C I A L T H A N K S
The string search algorithm used by the Find dialog was implemented by Mike Engber; all of the remaining source code for ZoneRanger was written by the author. One must also thank, however, Eric Hanig and Mike Engber for the numerous suggestions they have made regarding the feature set and user interface.
C O M M E N T S A N D S U G G E S T I O N S
Any comments and suggestions are welcome, and can be sent to the address below.
